Stacked on #1606 (iam-sdk-feature) — merge that one first. This is the second half of SDK-245: it makes the workload tokens registered by Sandbox.create's iam option usable, by letting a network rule's transform be a callback that receives placeholder strings the egress proxy resolves per request.

iam.tokens.aws is the literal string ${e2b.identity.tokens.aws} (the frozen backend spelling — a placeholder can only select a persisted named token, never an inline audience or claim). The SDK never resolves it: the wire payload carries the placeholder and the proxy substitutes a freshly minted JWT-SVID when it forwards the request, so the token value never reaches SDK-side code or the sandbox.

Referencing a name that isn't registered in iam.tokens fails with InvalidArgumentError / InvalidArgumentException listing the names that are — the proxy never turns an unregistered name into a token, so a typo would otherwise surface as a confusing auth failure at the destination. updateNetwork / update_network accepts the same callbacks, but its payload carries no iam config, so token names can't be validated client-side there and any name resolves to its placeholder.

Static transform: { headers } objects keep working unchanged (including hand-written ${e2b.identity.tokens.<name>} strings, which stay the escape hatch for tokens the SDK doesn't know about).

Only { iam } is exposed on the context for now — ${e2b.sandboxId} / ${e2b.teamId} / ${e2b.executionId} from the older prototype are not part of the current backend design, so sandbox can be added later when there is something to resolve.

Usage

import { Sandbox, Secret } from 'e2b'

const sandbox = await Sandbox.create({
  iam: {
    tokens: {
      aws: Secret.iamToken({ audience: 'sts.amazonaws.com', tokenType: 'JWT-SVID' }),
    },
  },
  network: {
    // Only allow egress to hosts that have rules registered.
    allowOut: ({ rules }) => [...rules.keys()],
    rules: {
      'api.internal.example.com': [
        {
          transform: ({ iam }) => ({
            headers: { Authorization: `Bearer ${iam.tokens.aws}` },
          }),
        },
      ],
    },
  },
})

from e2b import Sandbox, Secret

sandbox = Sandbox.create(
    iam={
        "tokens": {
            "aws": Secret.iam_token(audience="sts.amazonaws.com", token_type="JWT-SVID"),
        },
    },
    network={
        "allow_out": lambda ctx: list(ctx.rules.keys()),
        "rules": {
            "api.internal.example.com": [
                {
                    "transform": lambda ctx: {
                        "headers": {"Authorization": f"Bearer {ctx.iam.tokens['aws']}"},
                    },
                },
            ],
        },
    },
)

Both send:

{
  "iam": { "tokens": { "aws": { "audience": "sts.amazonaws.com", "tokenType": "JWT-SVID" } } },
  "network": {
    "allowOut": ["api.internal.example.com"],
    "rules": {
      "api.internal.example.com": [
        { "transform": { "headers": { "Authorization": "Bearer ${e2b.identity.tokens.aws}" } } }
      ]
    }
  }
}

Notes

• allowOut / deny_out selectors run before transforms are resolved, so ctx.rules still hands back the rules you passed — a rule's transform there is the union (object or callback), not the materialized object. The getInfo view keeps its own narrowed SandboxNetworkRuleInfo type.
• Every lookup form on iam.tokens is guarded, not just [name]: Python's map is a Mapping whose __getitem__ owns resolution (so .get('typo') raises instead of returning None), and membership ('aws' in ctx.iam.tokens / 'aws' in iam.tokens) answers "is it registered?" without raising so a callback can branch on it.
• A callback must be synchronous and return a plain transform object; a promise (from an async callback), an array, a Map/Date/class instance, or a missing return value is rejected with an actionable error rather than silently creating a rule with no headers. The awaitable is closed/caught so you don't also get an unawaited-coroutine warning or an unhandled rejection.
• Token lookup checks own keys only, so an unregistered name that collides with an object member (constructor, __proto__) reports as unregistered instead of resolving to a built-in. The four properties the runtime itself reads (toJSON, then, toString, valueOf) still resolve normally, so serializing, awaiting or coercing the map does not trip the guard.

Tests

New payload-level tests: JS tests/sandbox/networkTransform.test.ts (msw), Python tests/shared/sandbox/test_network_transform.py — shared rather than mirrored into the sync and async suites, since they only exercise the shared builders. They cover placeholder resolution, enumerating and membership-testing registered tokens, JSON.stringify of the context not tripping the guard, static transforms staying byte-identical, transform: null, the unregistered-name rejection through both [name] and .get(), the no-iam rejection, non-transform and async return values, and the permissive updateNetwork path.

Verified against production on all three surfaces (JS, sync Python, async Python), where:

1. a static transform carrying Bearer ${e2b.identity.tokens.aws} is accepted by validateNetworkRules and round-trips through getInfo / get_info unchanged;
2. the callback-resolved payload reaches the API and is answered with the expected team-gating error (400: Sandbox IAM workload tokens are not available for your team.), since iam is still feature-flagged;
3. a misspelled token name is rejected client-side before any request is made.

Proxy-side substitution of the placeholder ships separately in belt (EN-1864); until then the header value is forwarded verbatim, which is why there is no end-to-end injection test here.

Part of SDK-245.